<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!-- Copyright 1997 The Open Group, All Rights Reserved -->
<title>confstr</title>
</head><body bgcolor=white>
<center>
<font size=2>
The Single UNIX &reg; Specification, Version 2<br>
Copyright &copy; 1997 The Open Group

</font></center><hr size=2 noshade>
<h4><a name = "tag_000_002_005">&nbsp;</a>NAME</h4><blockquote>
confstr - get configurable variables
</blockquote><h4><a name = "tag_000_002_006">&nbsp;</a>SYNOPSIS</h4><blockquote>
<pre><code>

#include &lt;<a href="unistd.h.html">unistd.h</a>&gt;

size_t confstr(int <i>name</i>, char *<i>buf</i>, size_t <i>len</i>);
</code>
</pre>
</blockquote><h4><a name = "tag_000_002_007">&nbsp;</a>DESCRIPTION</h4><blockquote>
The
<i>confstr()</i>
function provides a method for applications
to get configuration-defined string values.
Its use and purpose are similar to
<i><a href="sysconf.html">sysconf()</a></i>,
but it is used where string values rather than numeric values are returned.
<p>
The
<i>name</i>
argument represents the system variable to be
queried.
The implementation supports the following name values,
defined in
<i><a href="unistd.h.html">&lt;unistd.h&gt;</a></i>.
It may support others:
<p>
<pre>
_CS_PATH
_CS_XBS5_ILP32_OFF32_CFLAGS
_CS_XBS5_ILP32_OFF32_LDFLAGS
_CS_XBS5_ILP32_OFF32_LIBS
_CS_XBS5_ILP32_OFF32_LINTFLAGS
_CS_XBS5_ILP32_OFFBIG_CFLAGS
_CS_XBS5_ILP32_OFFBIG_LDFLAGS
_CS_XBS5_ILP32_OFFBIG_LIBS
_CS_XBS5_ILP32_OFFBIG_LINTFLAGS
_CS_XBS5_LP64_OFF64_CFLAGS
_CS_XBS5_LP64_OFF64_LDFLAGS
_CS_XBS5_LP64_OFF64_LIBS
_CS_XBS5_LP64_OFF64_LINTFLAGS
_CS_XBS5_LPBIG_OFFBIG_CFLAGS
_CS_XBS5_LPBIG_OFFBIG_LDFLAGS
_CS_XBS5_LPBIG_OFFBIG_LIBS
_CS_XBS5_LPBIG_OFFBIG_LINTFLAGS
</pre>
<p>
If
<i>len</i>
is not 0, and if
<i>name</i>
has a configuration-defined value,
<i>confstr()</i>
copies that value into the
<i>len</i>-byte
buffer pointed to by
<i>buf</i>.
If the string to be returned is longer than
<i>len</i>
bytes, including the terminating null, then
<i>confstr()</i>
truncates the string to
<i>len</i>-1
bytes and null-terminates the result.
The application can detect that the string was truncated by
comparing the value returned by
<i>confstr()</i>
with
<i>len</i>.
<p>
If
<i>len</i>
is 0 and
<i>buf</i>
is a null pointer, then
<i>confstr()</i>
still returns the integer value as defined below, but does not
return a string.
If
<i>len</i>
is 0 but
<i>buf</i>
is not a null pointer, the result is unspecified.
</blockquote><h4><a name = "tag_000_002_008">&nbsp;</a>RETURN VALUE</h4><blockquote>
If
<i>name</i>
has a configuration-defined value,
<i>confstr()</i>
returns
the size of buffer that would be needed to hold the entire
configuration-defined value including the terminating null.
If this return value is greater than
<i>len</i>,
the string returned in
<i>buf</i>
is truncated.
<p>
If
<i>name</i>
is invalid,
<i>confstr()</i>
returns 0 and sets
<i>errno</i>
to indicate the error.
<p>
If
<i>name</i>
does not have a configuration-defined value,
<i>confstr()</i>
returns 0 and leaves
<i>errno</i>
unchanged.
<br>
</blockquote><h4><a name = "tag_000_002_009">&nbsp;</a>ERRORS</h4><blockquote>
The
<i>confstr()</i>
function will fail if:
<dl compact>

<dt>[EINVAL]<dd>
The value of the
<i>name</i>
argument is invalid.

</dl>
</blockquote><h4><a name = "tag_000_002_010">&nbsp;</a>EXAMPLES</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_002_011">&nbsp;</a>APPLICATION USAGE</h4><blockquote>
An application can distinguish between an invalid
<i>name</i>
parameter
value and one that corresponds to a configurable variable that has
no configuration-defined value by checking if
<i>errno</i>
is modified.
This mirrors the behaviour of
<i><a href="sysconf.html">sysconf()</a></i>.
<p>
The original need for this function was to provide a way of
finding the configuration-defined default value for the
environment variable
<i>PATH</i>.
Since
<i>PATH</i>
can be modified by the
user to include directories that could contain utilities
replacing <b>XCU</b> specification standard utilities, applications need a way
to determine the system-supplied
<i>PATH</i>
environment variable
value that contains the correct search path for the
standard utilities.
<p>
An application could use:
<pre>
<code>
confstr(name, (char *)NULL, (size_t)0)
</code>
</pre>
<p>
to find out how big a buffer is needed for the string value; use
<i><a href="malloc.html">malloc()</a></i>
to allocate a buffer to hold the string; and call
<i>confstr()</i>
again to get the string.
Alternately, it could allocate a fixed, static buffer that is big enough to
hold most answers (perhaps 512 or 1024 bytes), but then use
<i><a href="malloc.html">malloc()</a></i>
to allocate a larger buffer if it finds that this is too small.
</blockquote><h4><a name = "tag_000_002_012">&nbsp;</a>FUTURE DIRECTIONS</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_002_013">&nbsp;</a>SEE ALSO</h4><blockquote>
<i><a href="pathconf.html">pathconf()</a></i>,
<i><a href="sysconf.html">sysconf()</a></i>,
<i><a href="unistd.h.html">&lt;unistd.h&gt;</a></i>,
the <b>XCU</b> specification of <i><a href="../xcu/getconf.html">getconf</a></i>.
</blockquote><h4>DERIVATION</h4><blockquote>
Derived from the ISO POSIX-2 standard.
</blockquote><hr size=2 noshade>
<center><font size=2>
UNIX &reg; is a registered Trademark of The Open Group.<br>
Copyright &copy; 1997 The Open Group
<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]

</font></center><hr size=2 noshade>
</body></html>

